Inside Macintosh: QuickDraw GX Graphics /

Chapter 5 - Bitmap Shapes / Bitmap Shapes Reference

Functions / Getting and Setting Bitmap Geometries

GXSetBitmap

You can use the GXSetBitmap function to change the information in the geometry of a bitmap shape.

void GXSetBitmap(gxShape target, const gxBitmap *data,
                 const gxPoint *position);

target

A reference to the bitmap shape whose geometry you want to change.

data

A pointer to a gxBitmap structure containing new information for the geometry of the target bitmap shape.

position

A pointer to a gxPoint structure indicating the new bitmap position for the target bitmap shape.

DESCRIPTION

The GXSetBitmap function uses information you provide both in the gxBitmap structure pointed to by the data parameter and the gxPoint structure pointed to by the position parameter to change the information in the geometry of the bitmap shape referenced by the target parameter. If the target shape is not a bitmap shape, this function converts the target shape to a bitmap shape before setting the geometry of the shape.

You can change only the bitmap position by creating a gxPoint structure, setting its fields to reflect the new position, passing a pointer to it in the position parameter, and setting the data parameter to nil.

You can change other information in the geometry of the target bitmap shape by providing new information in a gxBitmap structure and passing a pointer to this structure in the data parameter.

If the pixel image of the target bitmap shape was not allocated by QuickDraw GX (for example, if you allocated the pixel image yourself before calling the GXNewBitmap function), then the GXSetBitmap function simply replaces the information in the geometry of the target bitmap shape with information from the fields of the gxBitmap structure pointed to by the data parameter.

However, if QuickDraw GX allocated the pixel image of the target bitmap shape, you can use this function to change the dimensions of the existing pixel image.

You can change the bitmap height by providing a new height in the height field of the gxBitmap structure. You can change the bitmap width by setting the rowBytes field to 0 and provide a new bitmap width in the width field of the bitmap geometry structure. In this case, QuickDraw GX calculates an appropriate number of bytes per row.

In either case, this function does not scale the original pixel image; instead, it changes the amount of memory allocated to hold the pixel image. If you decrease the dimensions of the pixel image, QuickDraw GX fits the pixels in the original pixel image into a smaller space in memory, thereby losing some of the original pixel values. If you increase the dimensions of the pixel image, QuickDraw GX allocates more memory (possibly moving the original pixel image), thereby adding uninitialized pixels to the pixel image.

If QuickDraw GX allocated the original pixel image, you can also change the pixel size of the bitmap shape. You provide the new pixel size in the pixelSize field of the gxBitmap structure and the GXSetBitmap function expands or compresses the image to fit in the new pixel size. If you specify a smaller pixel size than the original, this function redistributes the colors in the color space of the bitmap shape.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
size_of_bitmap_exceeds_implementation_limit
parameter_is_nil	(debugging version)
invalid_pixelSize	(debugging version)
bitmap_height_negative	(debugging version)
bitmap_width_negative	(debugging version)
bitmap_height_negative	(debugging version)
bitmap_rowBytes_negative	(debugging version)
bitmap_rowBytes_too_small	(debugging version)
bitmap_rowBytes_not_aligned	(debugging version)
bitmap_ptr_not_aligned	(debugging version)
bitmap_rowBytes_must_be_specified_for_user_image_buffer
	(debugging version)
colorSpace_out_of_range	(debugging version)
Warnings
shape_access_not_allowed	(debugging version)

SEE ALSO

For information about the gxBitmap structure, see "The Bitmap Geometry Structure" beginning on page 5-62.

For information about pixel images, bitmap height, bitmap width, pixel size, and number of rows per byte, see "Bitmap Geometries" beginning on page 5-5.

For a complete discussion of the QuickDraw GX color architecture, see the chapter "Color and Color-Related Objects" in Inside Macintosh: QuickDraw GX Objects.

To create a bitmap shape, use the GXNewBitmap function, which is described on page 5-66.

To obtain a copy of the information from the geometry of a bitmap shape, use the GXGetBitmap function, which is described on page 5-68.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help